A.1.  Conformance Class “Core”

A.2.  Conformance Class “Data Retrieval”

A.3.  Conformance Class “Zone Query”

A.4.  Conformance Class “Filtering Zone Queries with CQL2”

A.5.  Conformance Class “Root DGGS”

A.6.  Conformance Class “Collection DGGS”

A.7.  Conformance Class “Data Subsetting”

A.8.  Conformance Class “Data Custom Depths”

A.9.  Conformance Class “DGGS-JSON encoding for Zone Data”

A.10.  Conformance Class “GeoJSON encoding for Zone Data”

A.11.  Conformance Class “FG-JSON encoding for Zone Data”

A.12.  Conformance Class “GeoTIFF encoding for Zone Data”

A.13.  Conformance Class “netCDF encoding for Zone Data”

A.14.  Conformance Class “CoverageJSON encoding for Zone Data”

A.15.  Conformance Class “JPEG XL Encoding for Zone Data”

A.16.  Conformance Class “PNG encoding for Zone Data”

A.17.  Conformance Class “JSON encoding for Zone Data”

A.18.  Conformance Class “HTML encoding for Zone Listing”

A.19.  Conformance Class “Binary 64-bit integer encoding for Zone Listing”

A.20.  Conformance Class “GeoJSON encoding for Zone Listing”

A.21.  Conformance Class “FG-JSON encoding for Zone Listing”

A.22.  Conformance Class “GeoTIFF encoding for Zone Listing”

A.23.  Conformance Class “Operation IDs”

B.1.  JSON Schema for defining a DGGRS

{
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "description": "Discrete Global Grid System Reference System (DGGRS) Definition.",
  "type": "object",
  "required": [
    "dggs",
    "zirs",
    "subZoneOrder"
  ],
  "properties": {
    "title": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "uri": {
      "type": "string",
      "format": "uri",
      "description": "The authoritative URI associated with this DGGRS definition"
    },
    "dggs": {
      "type": "object",
      "description": "The hierarchical series of Discrete Global Grid upon which this DGGRS is based, including any parameters.",
      "properties": {
        "definition": {
          "description": "The base definition of the hierarchical series of Discrete Global Grid, which may be parameterized.",
          "type": "object",
          "required": [
            "spatialDimensions",
            "temporalDimensions"
          ],
          "properties": {
            "crs": {
              "allOf": [
                {
                  "description": "The native Coordinate Reference System (CRS) in which the geometry of the zones for this DGGS is defined."
                },
                {
                  "anyOf": [
                    {
                      "type": "string",
                      "format": "uri",
                      "example": "EPSG:7789"
                    }
                  ]
                }
              ]
            },
            "basePolyhedron": {
              "type": "string",
              "description": "The Type/Class of Polyhedron used to construct the Discrete Global Grid System - if it is constructued using a Base Polyhedron.",
              "example": "icosahedron"
            },
            "refinementRatio": {
              "description": "The ratio of the area of zones between two consecutive hierarchy level (the ratio of child zones to parent zones, also called the aperture).",
              "example": 9,
              "type": "integer"
            },
            "constraints": {
              "type": "object",
              "properties": {
                "cellAxisAligned": {
                  "description": "Set to true if all edges of the geometry of all zones are aligned with one of the axis of the `crs`.",
                  "type": "boolean",
                  "default": false
                },
                "cellConformal": {
                  "type": "boolean",
                  "default": false
                },
                "cellEquiAngular": {
                  "type": "boolean",
                  "default": false
                },
                "cellEquiDistant": {
                  "type": "boolean",
                  "default": false
                },
                "cellEqualSized": {
                  "description": "Set to true if the area of all zones is the same for a particular zone geometry type of any specifc discrete global grid of the DGGS hierarchy.",
                  "type": "boolean",
                  "default": false
                }
              }
            },
            "spatialDimensions": {
              "description": "Number of Spatial Dimensions defined by the Discrete Global Grid System.",
              "example": 2,
              "type": "integer"
            },
            "temporalDimensions": {
              "description": "Number of Temporal Dimensions defined by the Discrete Global Grid System.",
              "example": 0,
              "type": "integer"
            },
            "zoneTypes": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "triangle",
                  "square",
                  "hexagon",
                  "pentagon",
                  "rhombus"
                ]
              },
              "example": [
                "hexagon",
                "pentagon"
              ]
            },
            "refinementStrategy": {
              "description": "The refinement strategy used by the Discrete Global Grid System",
              "type": "array",
              "items": {
                 "type": "string",
                 "enum": [
                    "centredChildCell",
                    "nestedChildCell",
                    "nodeCentredChildCell",
                    "edgeCentredChildCell",
                    "faceCentredChildCell",
                    "solidCentredChildCell"
                 ]
              },
              "example": [ "nestedChildCell" ]
            }
          }
        },
        "parameters": {
          "description": "The optional parameters establishing a very specific Discrete Global Grid System, where each zone has a well-defined geometry.",
          "type": "object",
          "properties": {
            "ellipsoid": {
              "type": "string",
              "format": "uri",
              "description": "Globe Reference System Identifier/Specification",
              "example": [
                "EPGS:7019"
              ]
            },
            "orientation": {
              "type": "object",
              "properties": {
                "latitude": {
                  "description": "Reference Latitude in decimal degrees to fix the orientation of the polyhedron.",
                  "example": 0,
                  "type": "number"
                },
                "longitude": {
                  "description": "Reference Longitude in decimal degrees to fix the orientation of the polyhedron.",
                  "example": 0,
                  "type": "number"
                },
                "description": {
                  "type": "string"
                }
              },
              "required": [
                "longitude",
                "latitude"
              ]
            }
          }
        }
      }
    },
    "zirs": {
      "description": "The Zone Identifier Reference System used for this Discrete Global Grid System Reference System.",
      "type": "object",
      "required": [
        "textZIRS"
      ],
      "properties": {
        "textZIRS": {
          "description": "textual zone identifier indexing scheme",
          "type": "object",
          "required": [
            "description"
          ],
          "properties": {
            "description": {
              "type": "string",
              "examples": [
                "Topological Morton Code (Space Filling Curve) Identifier. With a Level 0 alphabetical identifier from 'A' to 'S' followed by a numeric reference from 1 to 9 for all subsequent levels representing the arrangement of child zones following a Morton (Z-code) subdivision of the parent zone. The length of the identifier represents the level of refinement.",
                "Universal Morton Code (Space Filling Curve) Identifier. An ellipsoidal bitwise concatenation of longitude and latitude direct position to form a direct Morton code. This can be used across multiple DGGS infrastructures to provide a common index structure that is fixed in nature regardless of the topological zone index used by each DGGS.",
                "An identifier comprised of three separate level, row and column components corresponding to an OGC 2D Tile Matrix Set tile identifier, where the individual component are represented by uppercase hexadecimal numbers separated by a hyphen.",
                "An identifier comprised of an uppercase letter representing a level (A for level 0, B for level 1...), followed by a number from 0 to 9 representing the root rhombus corresponding to the faces of an icosahedron, in a staircase order from the top-left to the bottom right of an ISEA planar projection after a 60 degrees clockwise rotation, followed by a hyphen, then by an uppercase hexadecimal number identifying a sub-zone starting to count from 0 in row-major order.",
                "An identifier comprised of an uppercase letter representing the ISEA9R level corresponding to the current even or immediate lower odd ISEA3H level (A for level 0, B for level 1...), followed by a number from 0 to 9 representing the root rhombus corresponding to the faces of an icosahedron, in a staircase order from the top-left to the bottom right of an ISEA planar projection after a 60 degrees clockwise rotation, followed by a hyphen, then by an uppercase hexadecimal number identifying a sub-zone starting to count from 0 in row-major order, followed by a second hyphen, then by a letter identifying a hexagonal or pentagonzal zone intersecting the sub-rhombus: A: even level regular zone B: even level North pole zone C: even level South pole zone D: odd level zone centered on rhombus vertex E: odd level zone top-right of rhombus vertex F: odd level zone bottom-right of rhombus vertex G: odd level North pole zone H: odd level South pole zone\n"
              ]
            },
            "type": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "string",
                  "enum": [
                    "hierarchicalConcatenation",
                    "ogc2DTMSHexLevelRowCol",
                    "levelRootFaceHexRowMajorSubZone"
                  ]
                }
              ]
            }
          }
        },
        "uint64ZIRS": {
          "description": "64-bit unsigned integer zone indexing scheme",
          "type": "object",
          "required": [
            "description"
          ],
          "properties": {
            "description": {
              "type": "string",
              "examples": [
                "A 64-bit integer with the 30 least significant bits corresponds to a column, the next 29 bits corresponding to a row, and the 5 most significant bits correspond to a level of an OGC 2D Tile Matrix Set identifier, with individual components using little endian.",
                "A 64-bit integer with the 3 least significant bits corresponding to a hexagonal or pentagonzal zone intersecting a sub-rhombus: 0: even level regular zone 1: even level North pole zone 2: even level South pole zone 3: odd level zone centered on rhombus vertex 4: odd level zone top-right of rhombus vertex 5: odd level zone bottom-right of rhombus vertex 6: odd level North pole zone 7: odd level South pole zone, the next 51 bits corresponding to a sub-rhombus index, the next 4 bits corresponding to a root rhombus, the next 5 bits corresponding to an associated ISEA9R level, and the last most significant bit always 0 for a valid zone identifier.\n"
              ]
            },
            "type": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "string",
                  "enum": [
                    "ogc2DTMSHexLevelRowCol"
                  ]
                }
              ]
            }
          }
        }
      }
    },
    "subZoneOrder": {
      "description": "The ordering used for this Discrete Global Grid System Reference System when encoding the values associated with sub-zones at any given depth relative to a parent zone.",
      "type": "object",
      "required": [
        "description"
      ],
      "properties": {
        "description": {
          "type": "string",
          "examples": [
            "The zones are ordered in tightly packed scanlines. Considering the ISEA planar projection, for odd level parent, zones are ordered left to right along a scanline and scanlines are ordered from top to bottom. For an even level parent, zones are ordered top to bottom along a scanline and scanlines are ordered from left to right. For an odd depth, scanlines start along a hexagon edge, whereas for even depths, scanlines start on a hexagon vertex."
          ]
        },
        "type": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "string",
              "enum": [
                "scanline",
                "spiralFromCenter",
                "mortonCurve",
                "hilbertCurve"
              ]
            }
          ]
        }
      }
    }
  }
}

Figure B.1 — JSON Schema for the DGGRS Definition

The following example JSON DGGRS definitions conform to this schema.

B.2.  ISEA9R DGGRS definition

The following DGGRS is for an axis-aligned and equal-area DGGS based on the Icosahedral Snyder Equal-Area (ISEA) planar projection (see PROJ and geogrid for open-source implementations) using rhombuses with a refinement ratio of 9. When the ISEA projection is rotated 60 degrees, sheared horizontally by 30 degrees and units are mapped to a 5×6 space, the zones become square and their edges are aligned with the CRS axes, while remaining equal-area. A 2D Tile Matrix Set can also be defined in this transformed CRS, allowing for compatibility with OGC API — Tiles, WMTS and traditional client and visualization software with no built-in DGGS functionality. This transformed CRS no longer preserves angles and distances, although the topology, indexing and surface geometry on the Earth model remains the same as in the original ISEA CRS where angles and distances are preserved.

{
   "title": "ISEA9R",
   "description": "An ISEA9R Discrete Global Grid Reference System using the standard ISEA orientation and WGS84 authalic sphere, a {level}{rootRhombus}-{hexSubZone} indexing system, and scanline-based sub-zone ordering. The ten root rhombuses are formed by combining two icosahedron triangles at their base. Depending on whether the ISEA planar CRS is rotated, sheared and scaled or not, the geometry of the zones are either squares or rhombuses, and the zone edges are either axis-aligned, or the angles and distances are preserved. In either case, the topology, indexing and surface geometry on the Earth model remains the same. The ISEA9R DGGS is a dual of the ISEA3H DGGS even levels (a vertex/node in ISEA9R is the centroid of an ISEA3H zone).",
   "uri": "https://www.opengis.net/def/dggrs/OGC/1.0/ISEA9R",
   "links": [ { "rel": "describedby", "href": "https://portal.ogc.org/files/?artifact_id=107432" } ],
   "dggs": {
      "definition": {
         "spatialDimensions": 2,
         "temporalDimensions": 0,
         "crs": "https://www.opengis.net/def/crs/OGC/0/ISEAr60hs30",
         "links": [
            { "rel": "related", "href": "https://doi.org/10.3138/27H7-8K88-4882-1752" },
            { "rel": "related", "href": "https://proj.org/en/9.3/operations/projections/isea.html" },
         ],
         "basePolyhedron": "icosahedron",
         "refinementRatio": 9,
         "refinementStrategy": [ "nestedChildCell" ],
         "constraints": {
            "cellAxisAligned": true,
            "cellEqualSized": true
         },
         "zoneTypes": [ "square" ],
      },
      "parameters": {
         "ellipsoid": "Authalic sphere based on [EPSG:7030] (WGS84) -- NOTE: No identifier defined yet? [ESPG:7048] exists for Authalic sphere based on GRS80 [EPSG:7019]",
         "orientation":
         {
            "description": "Standard ISEA orientation with a single icosahedron vertex falling on land",
            "latitude": 58.28252559,
            "longitude": 11.25
         }
      }
   },
   "zirs": {
      "textZIRS": {
         "description": "An identifier comprised of an uppercase letter representing a level (A for level 0, B for level 1...), followed by a number from 0 to 9 representing the root rhombus corresponding to the faces of an icosahedron, in a staircase order from the top-left to the bottom right of an ISEA planar projection after a 60 degrees clockwise rotation, followed by a hyphen, then by an uppercase hexadecimal number identifying a sub-zone starting to count from 0 in row-major order.",
         "type": "levelRootFaceHexRowMajorSubZone"
      },
      "uint64ZIRS": {
         "description": "A 64-bit integer with the 30 least significant bits corresponds to a column, the next 29 bits corresponding to a row, and the 5 most significant bits correspond to a level of an OGC 2D Tile Matrix Set identifier, with individual components using little endian.",
         "type": "ogc2DTMSHexLevelRowCol"
      }
   },
   "subZoneOrder": {
      "description": "The zones are ordered as scanlines in row-major order, left to right, then top to bottom, based on a CRS derived from the planar ISEA projection after rotating it 60 degrees clockwise and applying a 30 degrees horizontal shear.",
      "type": "scanline"
   }
}

Figure B.2 — DGGRS Definition for ISEA9R

Figure B.3 — The ISEA9R squared root rhombuses (level 0) in the rotated and sheared ISEA planar CRS mapped to a 5×6 space whose axes are aligned with the zone edges, compatible with a 2DTMS definition (imagery from NASA Earth Observatory’s Blue Marble: Next Generation)

Figure B.4 — The ISEA9R level 0 zone identifiers, shown in the original ISEA planar CRS (GEBCO 2014 bathymetry)

Figure B.5 — The ISEA9R level 1 zone identifiers, shown in the original ISEA planar CRS (GEBCO 2014 bathymetry)

B.3.  ISEA3H DGGRS definition

The following DGGRS is for an ISEA3H DGGS, also based on the ISEA planar projection, with hexagonal and pentagonal zones, and a refinement ratio of 3, using a zone reference system based in part on its dual relationship with the ISEA9R DGGS. The DGGS is considered equal-area, although the 12 pentagonal zones at any level occupy 5/6th of the area of hexagonal zones.

{
   "title": "ISEA3H",
   "description": "An ISEA3H Discrete Global Grid Reference System using the standard ISEA orientation and WGS84 authalic sphere, a zone indexing system based on an ISEA9R, and scanline-based ordering",
   "uri": "https://www.opengis.net/def/dggrs/OGC/1.0/ISEA3H",
   "links": [ { "rel": "describedby", "href": "https://portal.ogc.org/files/?artifact_id=107432" } ],
   "dggs": {
      "definition": {
         "spatialDimensions": 2,
         "temporalDimensions": 0,
         "crs": "https://www.opengis.net/def/crs/OGC/0/ISEA",
         "links": [
            { "rel": "related", "href": "https://doi.org/10.3138/27H7-8K88-4882-1752" },
            { "rel": "related", "href": "https://proj.org/en/9.3/operations/projections/isea.html" },
         ],
         "basePolyhedron": "icosahedron",
         "refinementRatio": 3,
         "refinementStrategy": [ "nestedChildCell", "nodeCentredChildCell" ],
         "constraints": {
            "cellEqualSized": true,
            "cellEquiAngular": true,
            "cellEquiDistant": true
         },
         "zoneTypes": [ "hexagon", "pentagon" ],
      },
      "parameters": {
         "ellipsoid": "Authalic sphere based on [EPSG:7030] (WGS84) -- NOTE: No identifier defined yet? [ESPG:7048] exists for Authalic sphere based on GRS80 [EPSG:7019]",
         "orientation":
         {
            "description": "Standard ISEA orientation with a single icosahedron vertex falling on land",
            "latitude": 58.28252559,
            "longitude": 11.25
         }
      }
   },
   "zirs": {
      "textZIRS": {
         "description": "An identifier comprised of an uppercase letter representing the ISEA9R level corresponding to the current even or immediate lower odd ISEA3H level (A for level 0, B for level 1...), followed by a number from 0 to 9 representing the root rhombus corresponding to the faces of an icosahedron, in a staircase order from the top-left to the bottom right of an ISEA planar projection after a 60 degrees clockwise rotation, followed by a hyphen, then by an uppercase hexadecimal number identifying a sub-zone starting to count from 0 in row-major order, followed by a second hyphen, then by a letter identifying a hexagonal or pentagonzal zone intersecting the sub-rhombus: A: even level regular zone B: even level North pole zone C: even level South pole zone D: odd level zone centered on rhombus vertex E: odd level zone top-right of rhombus vertex F: odd level zone bottom-right of rhombus vertex G: odd level North pole zone H: odd level South pole zone\n",
         "type": "levelRootFaceHexRowMajorSubZone"
      },
      "uint64ZIRS": {
         "description": "A 64-bit integer with the 3 least significant bits corresponding to a hexagonal or pentagonzal zone intersecting a sub-rhombus: 0: even level regular zone 1: even level North pole zone 2: even level South pole zone 3: odd level zone centered on rhombus vertex 4: odd level zone top-right of rhombus vertex 5: odd level zone bottom-right of rhombus vertex 6: odd level North pole zone 7: odd level South pole zone, the next 51 bits corresponding to a sub-rhombus index, the next 4 bits corresponding to a root rhombus, the next 5 bits corresponding to an associated ISEA9R level, and the last most significant bit always 0 for a valid zone identifier."
      }
   },
   "subZoneOrder": {
      "description": "The zones are ordered in tightly packed scanlines. Considering the ISEA planar projection, for odd level parent, zones are ordered left to right along a scanline and scanlines are ordered from top to bottom. For an even level parent, zones are ordered top to bottom along a scanline and scanlines are ordered from left to right. For an odd depth, scanlines start along a hexagon edge, whereas for even depths, scanlines start on a hexagon vertex.",
      "type": "scanline"
   }
}

Figure B.6 — DGGRS Definition for ISEA3H using indexing based on ISEA9R

Figure B.7 — The ISEA3H level 0 zones and associated identifiers (derived from ISEA9R level 0), shown on an ISEA planar projection (GEBCO 2014 bathymetry)

Figure B.8 — The ISEA3H level 1 zones and associated identifiers (derived from ISEA9R level 0), shown on an ISEA planar projection (GEBCO 2014 bathymetry)

Figure B.9 — The ISEA3H level 2 zones and associated identifiers (derived from ISEA9R level 1), shown on an ISEA planar projection (GEBCO 2014 bathymetry)

B.4.  GNOSIS Global Grid DGGRS definition

The following DGGRS is based on the variable width 2D Tile Matrix Set of the same name. The GNOSIS Global Grid is also axis-aligned, with the axes being the geographic latitude and longitude, and already corresponds to a registered 2DTMS. Through the variable width capability of the tile matrices, this DGGS approximates equal area. For example, at any refinement level, only 4 zones touch each pole. Since the error budget still exceeds the 1%, it cannot be considered equal area. However, the error is the same along a particular row of zones following latitude lines, and can easily be calculated. Since its native axes are latitude and longitude, no additional reprojection is required to import data to or export data from this DGGS.

{
   "title": "GNOSISGlobalGrid",
   "description": "A Discrete Global Grid Reference System based on the GNOSIS Global Grid 2D Tile Matrix Set, a {hexLevel}-{hexRow}-{hexCol} indexing system, and scanline-based sub-zone ordering. Making use of variable matrix widths, zones are divided by 4, unless they touch the pole, in which case the half touching the pole is not split longitude-wise. The error budget is ~-25.8/+66.0% from mean zone size (+/- 45.9% from median) up to level 25 (~849 cm² mean zones).",
   "uri": "https://www.opengis.net/def/dggrs/OGC/1.0/GNOSISGlobalGrid",
   "links": [ { "rel": "describedby", "href": "https://docs.ogc.org/is/17-083r4/17-083r4.html#toc58" } ],
   "dggs": {
      "definition": {
         "spatialDimensions": 2,
         "temporalDimensions": 0,
         "crs": "https://www.opengis.net/def/crs/EPSG/0/4326",
         "links": [
            { "rel": "related", "href": "https://www.opengis.net/def/tilematrixset/OGC/1.0/GNOSISGlobalGrid" }
         ],
         "basePolyhedron": "octahedron",
         "refinementRatio": 4,
         "refinementStrategy": [ "nestedChildCell" ],
         "constraints": {
            "cellAxisAligned": true
         },
         "zoneTypes": [ "rectangle" ],
      },
      "parameters": {
         "ellipsoid": "[EPSG:7030]"
         "orientation":
         {
            "latitude": 0,
            "longitude": 0
         }
      }
   },
   "zirs": {
      "textZIRS": {
         "description": "An identifier comprised of three uppercase hexadecimal numbers separated by hyphens representing the level, row and column of the GNOSIS Global Grid 2D Tile Matrix Set.",
         "type": "ogc2DTMSHexLevelRowCol"
      },
      "uint64ZIRS": {
         "description": "A 64-bit integer with the 30 least significant bits corresponds to a column, the next 29 bits corresponding to a row, and the 5 most significant bits correspond to a level of an OGC 2D Tile Matrix Set identifier, with individual components using little endian.",
         "type": "ogc2DTMSHexLevelRowCol"
      }
   },
   "subZoneOrder": {
      "description": "The zones are ordered as scanlines in row-major order, left to right, then top to bottom, based on the EPSG:4326 CRS.",
      "type": "scanline"
   }
}

Figure B.10 — DGGRS Definition for the GNOSIS Global Grid

Figure B.11 — The GNOSIS Global Grid level 0 zones and associated identifiers (GEBCO 2014 bathymetry)

Figure B.12 — The GNOSIS Global Grid level 1 zones and associated identifiers (GEBCO 2014 bathymetry)

Figure B.13 — The GNOSIS Global Grid level 2 zones and associated identifiers (GEBCO 2014 bathymetry)

C.1.  Collection description

DGGS resources can be attached to an OGC API — Common — Part 2 collection origin. The following global GEBCO 2014 bathymetry collection will be used as an example:

\https://maps.gnosis.earth/ogcapi/collections/gebco

An example JSON response for this collection description resource, as defined by Common — Part 2 and the Collection DGGS Requirement Class, is presented below, including a link to the list of available DGGRSs:

{
   "id" : "gebco",
   "title" : "GEBCO 2014",
   "description" : "General Bathymetric Chart of the Oceans (2014)",
   "attribution" : "General Bathymetric Chart of the Oceans (<a href='https://www.gebco.net/news_and_media/gebco_2014_grid.html'>GEBCO_2014</a>)",
   "extent" : {
      "spatial" : {
         "bbox" : [ [ -180, -90, 180, 90 ] ],
         "grid" : [
            { "cellsCount" : 65537, "resolution" : 0.0054931640625 },
            { "cellsCount" : 32769, "resolution" : 0.0054931640625 }
         ]
   } },
   "minScaleDenominator" : 2183915.0938621787354,
   "minCellSize" : 0.0054931640625,
   "links" : [
      { "rel" : "self", "title" : "Information about this GEBCO data collection",
        "href" : "/ogcapi/collections/gebco"
      },
      { "rel" : "[ogc-rel:schema]",  "title" : "Schema",
         "href" : "/ogcapi/collections/gebco/schema"
      },
      { "rel" : "[ogc-rel:queryables]",  "title" : "Queryables",
         "href" : "/ogcapi/collections/gebco/queryables"
      },
      { "rel" : "[ogc-rel:dggrs-list]", "title" : "Available DGGRSs for this GEBCO data collection",
        "href" : "/ogcapi/collections/gebco/dggs"
      }
   ]
}

C.2.  Listing available DGGRSs

Whether accessing DGGS resources for the root of an API/dataset or for a particular collection, the first DGGS-specific request made by a client would be to list the available DGGRSs. Following the link obtained from the previous example response, a client can determine which DGGRSs are supported by the API at that end-point:

\https://maps.gnosis.earth/ogcapi/collections/gebco/dggs

An example JSON response for this DGGRS list, as defined by the Core requirement class, is presented below:

{
   "links" : [
      { "rel" : "[ogc-rel:geodata]", "href" : "/ogcapi/collections/gebco" }
   ],
   "dggrs" : [
      {
         "id" : "GNOSISGlobalGrid",
         "title" : "GNOSIS Global Grid",
         "uri" : "[ogc-dggrs:GNOSISGlobalGrid]",
         "links" : [
            { "rel" : "self", "title" : "GNOSISGlobalGrid DGGRS for GEBCO",
              "href" : "/ogcapi/collections/gebco/dggs/GNOSISGlobalGrid" },
            { "rel" : "[ogc-rel:dggrs-definition]", "title" : "GNOSISGlobalGrid DGGRS definition",
              "href" : "/ogcapi/dggrs/GNOSISGlobalGrid"
            }
         ]
      },
      {
         "id" : "ISEA9R",
         "title" : "ISEA Aperture 9 Rhombic",
         "uri" : "[ogc-dggrs:ISEA9R]",
         "links" : [
            { "rel" : "self", "title" : "ISEA9R DGGRS for GEBCO",
              "href" : "/ogcapi/collections/gebco/dggs/ISEA9R"
            },
            { "rel" : "[ogc-rel:dggrs-definition]", "title" : "ISEA9R DGGRS definition",
              "href" : "/ogcapi/dggrs/ISEA9R"
            }
         ]
      },
      {
         "id" : "ISEA3H",
         "title" : "ISEA Aperture 3 Hexagonal",
         "uri" : "[ogc-dggrs:ISEA3H]"
         "links" : [
            { "rel" : "self", "title" : "ISEA3H DGGRS for GEBCO",
              "href" : "/ogcapi/collections/gebco/dggs/ISEA3H"
            },
            { "rel" : "[ogc-rel:dggrs-definition]", "title" : "ISEA3H DGGRS definition",
              "href" : "/ogcapi/dggrs/ISEA3H"
            }
         ]
      }
   ]
}

C.3.  Retrieving the description of a specific DGGRS

A client would then select a particular DGGRS of which it already has built-in knowledge, possibly using a software library implementing support for one or more DGGRS available from the server.

As a fallback, a client without native support for a particular DGGRS can still retrieve and interpret data from a server implementing support for both zone queries and data retrieval by performing a two-steps operation. First, the client can perform a zone query for an area of interest using the bbox query parameter. Then, the client can request data for the zones returned by this query in a georeferenced encoding which it understands and which is not tightly coupled with the DGGS (excluding e.g.,the DGGS-JSON encoding), such as GeoJSON or GeoTIFF. However, for such use cases, OGC API — DGGS does not present significant advantages over other OGC API data access mechanisms such as OGC API — Coverages, OGC API — Features or OGC API — Tiles.

In this example, the client selects the ISEA3H DGGRS (because it has built-in support for it) and follows the link to obtain a complete description of the DGGRS:

\https://maps.gnosis.earth/ogcapi/collections/gebco/dggs/ISEA3H

An example JSON response for this DGGRS description, as defined by the Core requirement class, is presented below. Note how the description is more comprehensive than the summary description included for each item in the previous DGGRS list response, including a description, a default (relative) depth as well as additional links and link templates.

{
   "id" : "ISEA3H",
   "title" : "ISEA Aperture 3 Hexagonal",
   "description" : "A Discrete Global Grid Reference System based on the Icosahedral Snyder Equal Area projection, with aperture 3 hexagonal zones, using an indexing scheme based on ISEA9R.",
   "uri" : "[ogc-dggrs:ISEA3H]",
   "defaultDepth": 10,
   "maxRefinementLevel": 18,
   "links" : [
      { "rel" : "self", "title" : "ISEA3H DGGRS for GEBCO",
        "href" : "/ogcapi/collections/gebco/dggs/ISEA3H"
      },
      { "rel" : "[ogc-rel:dggrs-definition]", "title" : "ISEA3H DGGRS definition",
        "href" : "/ogcapi/dggrs/ISEA3H"
      },
      { "rel" : "[ogc-rel:dggrs-zone-query]", "title" : "ISEA3H DGGRS Zone Query",
        "href" : "/ogcapi/collections/gebco/dggs/ISEA3H/zones"
      },
      { "rel" : "[ogc-rel:geodata]", "href" : "/ogcapi/collections/gebco" }
   ],
   "linkTemplates" : [
      {
         "rel" : "[ogc-rel:dggrs-zone-info]",
         "title" : "DGGRS zone information for a particular ISEA3H zone",
         "href" : "/ogcapi/collections/gebco/dggs/ISEA3H/zones/{zoneId}"
      },
      {
         "rel" : "[ogc-rel:dggrs-zone-data]",
         "title" : "Data retrieval for a particular ISEA3H zone",
         "href" : "/ogcapi/collections/gebco/dggs/ISEA3H/zones/{zoneId}/data"
      }
   ]
}

See the informative annex B for examples of DGGRS definition responses which the client could obtain by following the [ogc-rel:dggrs-definition] links. The annex includes provisionary definitions for the ISEA3H, ISEA9R and GNOSIS Global Grid used in these examples which will likely be used to initially populate an authoritative registry, Additional DGGRS entries would be submitted, reviewed and registered based on the needs of the community.

C.4.  Retrieving information for a specific DGGRS zone

Later examples will demonstrate how to list available zones by performing zone queries, but for now these examples will skip directly to retrieving information about a particular zone. This capability, also defined in the Core requirement class, exists primarily for completeness of the API resource tree, for allowing to explore datasets using a browser interface, as well as for educational, demonstration and debugging purposes. An actual DGGS API client for visualization or performing analytics would normally not access this resource at all, since URL templates allow to directly access the data for a particular zone. While the Core requirement class makes a number of recommendations about statistical information and topological relationships that should be included in the zone information resource, clients may not rely on any of this information being present. Clients can instead rely on their own local software libraries to establish topological relationships, can use zone queries to pose questions that can be answered by a list of zone IDs, or can retrieve zone data packets containing values from multiple sub-zones to perform their own analytics. A future extension could also introduce mandatory requirements making some of the recommended content such as summary statistics or additional useful information mandatory, which clients could then rely on for conforming implementations.

This example assumes a client does for some reason request information in a JSON representation about a particular ISEA3H DGGRS zone, say E6-317-A, based on its built-in support for that DGGRS (perhaps this client is an Executable Test Suite, since implementing this resource is still required to conform to the Core conformance class, including at minimum an id and links to the DGGRS and data retrieval, if applicable). The GET request URL and response for this zone information resource associated with the GEBCO collection would then look like the following:

\https://maps.gnosis.earth/ogcapi/collections/gebco/dggs/ISEA3H/zones/E6-317-A

{
   "id" : "E6-317-A",
   "links" : [
      { "rel" : "[ogc-rel:geodata]", "href" : "/ogcapi/collections/gebco" },
      { "rel" : "[ogc-rel:dggrs]", "title" : "ISEA3H DGGRS for GEBCO",
        "href" : "/ogcapi/collections/gebco/dggs/ISEA3H"
      },
      { "rel" : "[ogc-rel:dggrs-definition]", "title" : "ISEA3H DGGRS definition",
        "href" : "/ogcapi/dggrs/ISEA3H"
      },
      { "rel" : "[ogc-rel:dggrs-zone-data]", "title" : "ISEA3H Zone E6-317-A data for GEBCO",
        "href" : "/ogcapi/collections/gebco/dggs/ISEA3H/zones/E6-317-A/data"
      },

      { "rel" : "[ogc-rel:dggrs-zone-parent]", "title": "Parent zone D6-65-E",
        "href" : "/ogcapi/collections/gebco/dggs/ISEA3H/zones/D6-65-E" },
      { "rel" : "[ogc-rel:dggrs-zone-parent]", "title": "Parent zone D6-4A-F",
        "href" : "/ogcapi/collections/gebco/dggs/ISEA3H/zones/D6-4A-F" },
      { "rel" : "[ogc-rel:dggrs-zone-parent]", "title": "Parent zone D6-66-D (centroid child)",
        "href" : "/ogcapi/collections/gebco/dggs/ISEA3H/zones/D6-66-D" },

      { "rel" : "[ogc-rel:dggrs-zone-child]", "title": "Child zone E6-317-D (centroid child)",
        "href" : "/ogcapi/collections/gebco/dggs/ISEA3H/zones/E6-317-D" },
      { "rel" : "[ogc-rel:dggrs-zone-child]", "title": "Child zone E6-317-E (vertex child)",
        "href" : "/ogcapi/collections/gebco/dggs/ISEA3H/zones/E6-317-E" },
      { "rel" : "[ogc-rel:dggrs-zone-child]", "title": "Child zone E6-317-F (vertex child)",
        "href" : "/ogcapi/collections/gebco/dggs/ISEA3H/zones/E6-317-F" },
      { "rel" : "[ogc-rel:dggrs-zone-child]", "title": "Child zone E6-316-E (vertex child)",
        "href" : "/ogcapi/collections/gebco/dggs/ISEA3H/zones/E6-316-E" },
      { "rel" : "[ogc-rel:dggrs-zone-child]", "title": "Child zone E6-2C5-F (vertex child)",
        "href" : "/ogcapi/collections/gebco/dggs/ISEA3H/zones/E6-2C5-F" },
      { "rel" : "[ogc-rel:dggrs-zone-child]", "title": "Child zone E6-2C5-E (vertex child)",
        "href" : "/ogcapi/collections/gebco/dggs/ISEA3H/zones/E6-2C5-E" },
      { "rel" : "[ogc-rel:dggrs-zone-child]", "title": "Child zone E6-2C6-F (vertex child)",
        "href" : "/ogcapi/collections/gebco/dggs/ISEA3H/zones/E6-2C6-F" },

      { "rel" : "[ogc-rel:dggrs-zone-neighbor]", "title": "Neighboring zone E6-2C5-A (left)",
        "href" : "/ogcapi/collections/gebco/dggs/ISEA3H/zones/E6-2C5-A" },
      { "rel" : "[ogc-rel:dggrs-zone-neighbor]", "title": "Neighboring zone E6-369-A (right)",
        "href" : "/ogcapi/collections/gebco/dggs/ISEA3H/zones/E6-369-A" },
      { "rel" : "[ogc-rel:dggrs-zone-neighbor]", "title": "Neighboring zone E6-2C6-A (top-left)",
        "href" : "/ogcapi/collections/gebco/dggs/ISEA3H/zones/E6-2C6-A" },
      { "rel" : "[ogc-rel:dggrs-zone-neighbor]", "title": "Neighboring zone E6-318-A (top-right)",
        "href" : "/ogcapi/collections/gebco/dggs/ISEA3H/zones/E6-318-A" },
      { "rel" : "[ogc-rel:dggrs-zone-neighbor]", "title": "Neighboring zone E6-316-A (bottom-left)",
        "href" : "/ogcapi/collections/gebco/dggs/ISEA3H/zones/E6-316-A" },
      { "rel" : "[ogc-rel:dggrs-zone-neighbor]", "title": "Neighboring zone E6-368-A (bottom-right)",
        "href" : "/ogcapi/collections/gebco/dggs/ISEA3H/zones/E6-368-A" }
   ],
   "shapeType" : "hexagon",
   "areaMetersSquare" : 7765218521.3124237060547,
   "level": 8,
   "crs": "[OGC:CRS84]",
   "centroid": [ 34.8301691522937, 45.493496839407 ],
   "bbox": [ 34.1122890215028, 45.0307065899164, 35.5548602543606, 45.9545736562164 ],
   "statistics" : {
      "Elevation" : {
         "minimum": -56.415161132812,
         "maximum": 499.67742919922,
         "average": 34.243211554643,
         "stdDev": 58.802922870029
      }
   },
   "geometry" : {
      "type" : "Polygon",
      "coordinates" : [
         [ [35.0325792437483, 45.9545736562164], [35.0675730384768, 45.9355692576877],
         [35.1025417108968, 45.9165538942826], [35.1374852871664, 45.8975275789752],
         [35.1724037934654, 45.8784903247104], [35.2072972559966, 45.859442144404],
         [35.2421657009844, 45.8403830509428], [35.2770091546753, 45.8213130571846],
         [35.3118276433383, 45.8022321759581], [35.3466211932639, 45.7831404200626],
         [35.3813898307646, 45.7640378022689], [35.4161335821748, 45.7449243353179],
         [35.4508524738509, 45.725800031922], [35.4855465321706, 45.7066649047642],
         [35.5202157835335, 45.6875189664983], [35.5548602543606, 45.6683622297491],
         [35.5409621444686, 45.6377043376462], [35.527097993237, 45.6070377035762],
         [35.5132676379054, 45.576362404245], [35.4994709165275, 45.5456785157748],
         [35.4857076679667, 45.5149861137079], [35.4719777318922, 45.4842852730117],
         [35.4582809487756, 45.4535760680823], [35.4446171598862, 45.4228585727495],
         [35.4309862072879, 45.3921328602809], [35.4173879338344, 45.3613990033857],
         [35.4038221831664, 45.3306570742198], [35.390288799707, 45.2999071443891],
         [35.376787628658, 45.2691492849539], [35.3633185159963, 45.2383835664335],
         [35.3498813084697, 45.2076100588098], [35.3020092883842, 45.1959626800988],
         [35.2541667920171, 45.1842941045825], [35.2063537245807, 45.1726044068217],
         [35.1585699921521, 45.1608936605836], [35.1108155016624, 45.1491619388553],
         [35.0630901608873, 45.1374093138529], [35.0153938784362, 45.1256358570339],
         [34.9677265637424, 45.1138416391074], [34.9200881270535, 45.1020267300452],
         [34.8724784794212, 45.0901911990919], [34.8248975326921, 45.0783351147756],
         [34.7773451994982, 45.0664585449175], [34.7298213932474, 45.0545615566424],
         [34.6823260281141, 45.0426442163884], [34.6348590190306, 45.0307065899164],
         [34.6001893100315, 45.0496582358553], [34.565495668238, 45.0685988693406],
         [34.5307780684752, 45.0875284779916], [34.4960364855943, 45.1064470494011],
         [34.4612708944723, 45.1253545711343], [34.4264812700118, 45.1442510307293],
         [34.3916675871419, 45.163136415697], [34.3568298208172, 45.1820107135215],
         [34.3219679460187, 45.2008739116594], [34.2870819377534, 45.2197259975403],
         [34.2521717710543, 45.2385669585668], [34.2172374209808, 45.2573967821143],
         [34.1822788626187, 45.2762154555309], [34.1472960710798, 45.2950229661379],
         [34.1122890215028, 45.3138193012292], [34.1249230545728, 45.34474018811],
         [34.1375863824436, 45.3756544566371], [34.1502791448219, 45.4065620478253],
         [34.1630014821059, 45.4374629022505], [34.1757535353903, 45.4683569600458],
         [34.1885354464684, 45.4992441608991], [34.2013473578361, 45.5301244440496],
         [34.2141894126955, 45.5609977482844], [34.2270617549581, 45.5918640119347],
         [34.2399645292484, 45.6227231728739], [34.2528978809076, 45.6535751685123],
         [34.2658619559968, 45.6844199357953], [34.2788569013007, 45.7152574111995],
         [34.2918828643314, 45.7460875307289], [34.3049399933312, 45.7769102299116],
         [34.3532293127776, 45.7889076311011], [34.4015496229923, 45.8008834941054],
         [34.4499010211884, 45.8128377421031], [34.4982836054328, 45.8247702974718],
         [34.5466974746559, 45.8366810817765], [34.5951427286622, 45.8485700157587],
         [34.64361946814, 45.8604370193242], [34.6921277946726, 45.8722820115316],
         [34.7406678107482, 45.8841049105797], [34.7892396197712, 45.8959056337956],
         [34.8378433260726, 45.9076840976223], [34.8864790349218, 45.919440217605],
         [34.9351468525365, 45.9311739083794], [34.9838468860951, 45.9428850836581],
         [35.0325792437483, 45.9545736562164] ]
      ]
   }
}

An HTML representation of that zone information resource, allowing a user to browse through parent, children and neighboring zones, could look like the following:

Figure C.1 — Sample HTML response of an ISEA3H DGGRS zone information resource for GEBCO data

C.5.  Simple zone queries

Having selected a particular DGGRS, one use case for the API is for a client to perform spatial queries by requesting a list of zones. The simplest case is to simply request a list of all available zones for a discrete global grid of a given refinement level (zone-level), which in the case of a particular collection implies zones for which the collection has data.

C.5.1.  Querying a particular refinement level

If no zone-level parameter is provided, the server is free to pick a default zone level for such queries, which would result in a reasonable number of zones returned, based on the area and resolution of the data collection. In this example, the client will explicitly request a list of zones at refinement level 1.

By default, if compact-zones=false is not specified by the client, zone queries are compacted, meaning that if all sub-zones of a parent zone would be included in the response, they get replaced by that parent zone so that fewer zones need to be enumerated. This can result in zones of a lower refinement level being returned than the requested zone-level, and therefore a mix of zones of different levels. A full globe response would thereore always result in the list of all zones of refinement level 0. In these examples, the client will explicitly set compact-zones=false.

Following the [ogc-rel:dggrs-zone-query] link, specifying these parameters, and negotiating a JSON zone list response using an Accept: application/json header, the client requests from the end-point:

\https://maps.gnosis.earth/ogcapi/collections/gebco/dggs/ISEA3H/zones?zone-level=1&compact-zones=false

An example JSON response for this Zone Query JSON, as defined by the Zone Query requirement class, is presented below:

{
   "zones" : [
      "A0-0-D", "A0-0-E", "A0-0-F", "A0-0-G", "A1-0-D", "A1-0-E",
      "A1-0-F", "A2-0-D", "A2-0-E", "A2-0-F", "A3-0-D", "A3-0-E",
      "A3-0-F", "A4-0-D", "A4-0-E", "A4-0-F", "A5-0-D", "A5-0-E",
      "A5-0-F", "A6-0-D", "A6-0-E", "A6-0-F", "A7-0-D", "A7-0-E",
      "A7-0-F", "A8-0-D", "A8-0-E", "A8-0-F", "A9-0-D", "A9-0-E",
      "A9-0-F", "A9-0-H"
   ],
   "links" : [
      { "rel" : "[ogc-rel:dggrs]", "title" : "ISEA3H DGGS for GEBCO",
        "href" : "/ogcapi/collections/gebco/dggs/ISEA3H"
      },
      { "rel" : "[ogc-rel:dggrs-definition]", "title" : "ISEA3H DGGRS definition",
         "href" : "/ogcapi/dggrs/ISEA3H"
      },
      { "rel" : "[ogc-rel:geodata]", "href" : "/ogcapi/collections/gebco" }
   ],
   "linkTemplates" : [
      { "rel" : "[ogc-rel:dggrs-zone-data]", "title" : "ISEA3H data for GEBCO",
        "href" : "/ogcapi/collections/gebco/dggs/ISEA3H/zones/{zoneId}/data",
      }
   ]
}

The server returned all 32 zones of ISEA3H level 1 (which corresponds to a truncated icosahedron — the traditional soccer ball pattern), because the collection has global coverage.

Servers may support additional representations of zone lists beyond JSON, such as a more compact binary 64-bit integers encoding, a GeoJSON representation including zone geometry or an HTML representation for exploring datasets in a browser through the DGGS API. Note that regardless of encoding, zone query responses can also be compressed for additional banwidth efficiency if the client and server negotiate a content encoding e.g., using Content-Encoding: gzip.

CAUTION

The transfer of zone geometry in zone queries is not an efficient use of the DGGS API for practical analytics purposes, since clients should already have built-in knowledge of the selected DGGRS in their local software libraries and can efficiently infer the geometry of a zone from its zone ID alone as needed. In many use cases, the geometry may not be needed at all.

The ability to retrieve zone lists in a geospatial data format such as GeoJSON or GeoTIFF which can readily be visualized in GIS tools is useful for educational, demonstration and debugging purposes. For example, this functionality can be used to generate grids, such as those seen in annex B (a crs parameter to request an ISEA planar projection was used in that case to override the default GeoJSON CRS84), as well as the zone visualizations seen in the examples in this section.

A visualization of the response from negotiating application/geo+json for the above request is seen below.

Figure C.2 — GeoJSON response for zone query for ISEA3H DGGRS at level 1 visualized in QGIS

C.5.2.  Querying for a spatio-temporal subset

To request a list of zones for an area of interest, the bbox or subset query parameter can be used. For temporal datasets, the datetime can be used as well as subset=time(…​) to constrain the query to a time of interest. For restricting the same zone query to a bounding box area from (40°N, 30°E) to (60°N,50°E), the client could make either of the following requests:

\https://maps.gnosis.earth/ogcapi/collections/gebco/dggs/ISEA3H/zones?bbox=30,40,50,60&zone-level=1&compact-zones=false

\https://maps.gnosis.earth/ogcapi/collections/gebco/dggs/ISEA3H/zones?subset=Lat(40:60),Lon(30:50)&zone-level=1&compact-zones=false

and obtain the following response (negotiating a JSON zone list again):

{
   "zones" : [ "A0-0-G", "A6-0-E" ],
   "links" : [
      { "rel" : "[ogc-rel:dggrs]", "title" : "ISEA3H DGGS for GEBCO",
        "href" : "/ogcapi/collections/gebco/dggs/ISEA3H"
      },
      { "rel" : "[ogc-rel:dggrs-definition]", "title" : "ISEA3H DGGRS definition",
         "href" : "/ogcapi/dggrs/ISEA3H"
      },
      { "rel" : "[ogc-rel:geodata]", "href" : "/ogcapi/collections/gebco" }
   ],
   "linkTemplates" : [
      { "rel" : "[ogc-rel:dggrs-zone-data]", "title" : "ISEA3H data for GEBCO",
        "href" : "/ogcapi/collections/gebco/dggs/ISEA3H/zones/{zoneId}/data",
      }
   ]
}

This time, the server returned only two zones of ISEA3H level 1.

A visualization of the response from negotiating application/geo+json for the above request, together with the bounding box used, is seen below.

Figure C.3 — GeoJSON response for zone query for ISEA3H DGGRS at level 1 for a (40°N, 30°E) to (60°N,50°E) bounding box visualized in QGIS

As seen below, an HTML representation could include rendered previews of the data for the zone area, summary information, as well as links to retrieve the data and access the zone information resource for each zone. Note that the significant variance in area (-11.31% and +6.66% from the reference mean zone (whose area is calculated by dividing the Earth surface area by the total number of zones) is due to the the fact that A0-0-G is a pentagon (in the ISEA projection — on the Earth surface it looks more like a decagon) which occupies 5/6th the area of hexagons such as A6-0-E (which on the Earth surface is one of the hexagons appearing as a nonagon), as well as the fact that at level 1, the number of pentagons (12) is significant compared to the total number of zones (32).

Figure C.4 — Sample HTML response for a zone query for ISEA3H DGGRS at level 1 for a (40°N, 30°E) to (60°N,50°E) bounding box

Of course with a higher zone level, many more zones can be returned:

\https://maps.gnosis.earth/ogcapi/collections/gebco/dggs/ISEA3H/zones?bbox=30,40,50,60&zone-level=8&compact-zones=false

Figure C.5 — Sample HTML response for a zone query for ISEA3H DGGRS at level 8 for a (40°N, 30°E) to (60°N,50°E) bounding box

C.5.3.  Zones representing data availability

The primary purpose of the Zone Query requirement class is to ask questions of the type “Where is it?”. The answer is a region of space-time represented by a list of zones. This region might correspond to where data is available for a particular collection, may be the result of a processing workflow, or the result of evaluating a CQL2 query expression as demonstrated in later examples. This result could otherwise have been communicated as a multi-polygon vector mask or as a rasterized 1-bit image or opacity channel.

The following example illustrates the case of a collection (elevation data from Viewfinder Panoramas) which does not have data for everywhere on the globe (only over land), using a higher zone level of 6 for the query.

\https://maps.gnosis.earth/ogcapi/collections/SRTM_ViewFinderPanorama/dggs/ISEA3H/zones?zone-level=6&compact-zones=false

Figure C.6 — GeoJSON response for zone query for ISEA3H DGGRS at level 6 for a Viewfinder Panoramas land elevation collection, visualized in QGIS

Using a bounding box to restrict the query to an area of interest, a higher zone level of 10 could be used:

\https://maps.gnosis.earth/ogcapi/collections/SRTM_ViewFinderPanorama/dggs/ISEA3H/zones?zone-level=10&bbox=30,40,50,50&compact-zones=false

Figure C.7 — GeoJSON response for zone query for ISEA3H DGGRS at level 10, using a (40°N, 30°E) to (40°N,50°E) bounding box, for a Viewfinder Panoramas land elevation collection, visualized in QGIS

The DGGS API works independently of the nature of the data, whether dealing with gridded coverage or vector features, allowing to easily perform complex analytics involving heterogeneous data sources. The previous examples all used gridded coverage data sources. The following example illustrates the same capabilities using the Natural Earth states and provinces collection:

\https://maps.gnosis.earth/ogcapi/collections/NaturalEarth:cultural:ne_10m_admin_1_states_provinces/dggs/ISEA3H/zones?zone-level=6&compact-zones=false

Figure C.8 — GeoJSON response for zone query for ISEA3H DGGRS at level 6, for a Natural Earth states and provinces collection, visualized in QGIS

The similarity between the response for this collection of states and provinces features compared to the same request earlier for a gridded elevation coverages showcases the potential for DGGS zone queries to facilitate data integration.

C.5.4.  Querying sub-zones of a parent zone

The Zone Query requirement class defines the parent-zone query parameter as one more way how to restrict the query spatially (and temporally in the case of a temporal DGGRS), which is particularly useful for hierarchical exploration. For example, to restrict the query to sub-zones of A6-0-E rather than using a bounding box, the client could perform the following request (at level 8):

\https://maps.gnosis.earth/ogcapi/collections/SRTM_ViewFinderPanorama/dggs/ISEA3H/zones?zone-level=8&parent-zone=A6-0-E&compact-zones=false

Figure C.9 — GeoJSON response for zone query for ISEA3H DGGRS at level 8, for parent zone A6-0-E, for a Viewfinder Panoramas land elevation collection, visualized in QGIS

The client could then pick one of the returned zones, say E6-317-A, for deeper exploration at level 16:

\https://maps.gnosis.earth/ogcapi/collections/SRTM_ViewFinderPanorama/dggs/ISEA3H/zones?zone-level=16&parent-zone=E6-317-A&compact-zones=false

Figure C.10 — GeoJSON response for zone query for ISEA3H DGGRS at level 16, for parent zone E6-317-A, for a Viewfinder Panoramas land elevation collection, visualized in QGIS

Going back to A6-0-E (a level 1 zone), this could also be used to retrieve the immediate children by requesting the next level (2), to step down the hierarchy a single refinement level at a time:

\https://maps.gnosis.earth/ogcapi/collections/SRTM_ViewFinderPanorama/dggs/ISEA3H/zones?zone-level=2&parent-zone=A6-0-E&compact-zones=false

The 7 children zones (1 centroid child and 6 vertex children) are returned, since they all contain data.

Figure C.11 — GeoJSON response for zone query for ISEA3H DGGRS at level 2, for parent zone A6-0-E (outline shown), for a Viewfinder Panoramas land elevation collection, visualized in QGIS

C.5.5.  ISEA9R (rhombus) Zone Queries

Although all examples so far used the ISEA3H DGGRS, this DGGS API is completely agnostic of the DGGRS. Future planned parts for OGC Abstract Topic 21 will standardize new categories of DGGS, including volumetric (Part 2), temporal (Part 3) and axis-aligned (Part 4). The DGGS API functionality, as demonstrated in this examples section, is ready to handle all any DGGRS, including DGGRS based on these new DGGS types.

The following examples demonstrates equivalent zone queries using the ISEA9R DGGS, a dual DGGS of ISEA3H even refinement levels, which can be considered axis-aligned in a CRS derived from rotating and shearing the ISEA planar projection. In the ISEA planar projection, the ISEA9R zones are shaped as rhombuses.

\https://maps.gnosis.earth/ogcapi/collections/SRTM_ViewFinderPanorama/dggs/ISEA9R/zones?zone-level=3&compact-zones=false

Figure C.12 — GeoJSON response for zone query for ISEA9R DGGRS at level 3 for a Viewfinder Panoramas land elevation collection visualized in QGIS

\https://maps.gnosis.earth/ogcapi/collections/gebco/dggs/ISEA9R/zones?bbox=30,40,50,60&zone-level=4&compact-zones=false

Figure C.13 — GeoJSON response for zone query for ISEA9R DGGRS at level 4 for a (40°N, 30°E) to (60°N,50°E) bounding box visualized in QGIS

\https://maps.gnosis.earth/ogcapi/collections/SRTM_ViewFinderPanorama/dggs/ISEA9R/zones?zone-level=4&parent-zone=B6-2&compact-zones=false

Figure C.14 — GeoJSON response for zone query for ISEA9R DGGRS at level 4 for parent zone B6-2, for a Viewfinder Panoramas, visualized in QGIS

\https://maps.gnosis.earth/ogcapi/collections/SRTM_ViewFinderPanorama/dggs/ISEA9R/zones?zone-level=8&parent-zone=E6-317&compact-zones=false

Figure C.15 — GeoJSON response for zone query for ISEA9R DGGRS at level 8 for parent zone E6-317, for a Viewfinder Panoramas, visualized in QGIS

Although ISEA9R is axis-aligned, like ISEA3H, it is equal area, with an error budget below 1%.

C.5.6.  GNOSIS Global Grid (WGS84 rectangles) Zone Queries

The next zone query examples use the GNOSIS Global Grid DGGRS. The GNOSIS Global Grid is also axis-aligned, with the axes being the geographic latitude and longitude. On a plate carée projection, the zones are shaped as rectangles, which conveniently correspond to typical EPSG:4326 / CRS84 bounding boxes.

\https://maps.gnosis.earth/ogcapi/collections/SRTM_ViewFinderPanorama/dggs/ISEA3H/zones?zone-level=5&compact-zones=false

Figure C.16 — GeoJSON response for zone query for GNOSIS Global Grid DGGRS at level 5 for a Viewfinder Panoramas land elevation collection visualized in QGIS

\https://maps.gnosis.earth/ogcapi/collections/gebco/dggs/GNOSISGlobalGrid/zones?bbox=30,40,50,60&zone-level=7&compact-zones=false

Figure C.17 — GeoJSON response for zone query for GNOSIS Global Grid DGGRS at level 7 for a (40°N, 30°E) to (60°N,50°E) bounding box visualized in QGIS

\https://maps.gnosis.earth/ogcapi/collections/SRTM_ViewFinderPanorama/dggs/GNOSISGlobalGrid/zones?zone-level=8&parent-zone=2-2-9&compact-zones=false

Figure C.18 — GeoJSON response for zone query for GNOSIS Global Grid DGGRS at level 8 for parent zone 2-2-9, for a Viewfinder Panoramas, visualized in QGIS

\https://maps.gnosis.earth/ogcapi/collections/SRTM_ViewFinderPanorama/dggs/GNOSISGlobalGrid/zones?zone-level=13&parent-zone=6-1F-98&compact-zones=false

Figure C.19 — GeoJSON response for zone query for GNOSIS Global Grid DGGRS at level 13 for parent zone 6-1F-98, for a Viewfinder Panoramas, visualized in QGIS

C.6.  Compact zone queries

The following examples are reprises of some of the earlier ones leaving compact zones enabled, showcasing the fewer zones being returned to communicate an identical spatial area.

C.6.1.  ISEA3H compact zone queries

Compacting ISEA3H zones is complicated by the fact that sub-zones are not fully congruent. The approach demonstrated here skips a refinement level, taking advantage of the fact that 7 of the grand-children of a zone are congruent. Overlaps are seen, as 6 holes are left at the vertices of the grand-parent, each occupying 1/3rd the size of a congruent grand-child. Note how 7 + 6 x 1/3 = 9 (3 x 3), which corresponds to the two subsequent refinements at the refinement ratio of 3. If the neighboring grand-parent of the same refinement level cannot be used, then the non-congruent vertex children must be included, resulting in these overlaps.

\https://maps.gnosis.earth/ogcapi/collections/gebco/dggs/ISEA3H/zones?bbox=30,40,50,60&zone-level=8

Figure C.20 — GeoJSON compact zones response querying ISEA3H DGGRS at level 8 for a (40°N, 30°E) to (60°N,50°E) bounding box

\https://maps.gnosis.earth/ogcapi/collections/SRTM_ViewFinderPanorama/dggs/ISEA3H/zones?zone-level=6

Figure C.21 — GeoJSON compact zones response for querying ISEA3H DGGRS at level 6 for a Viewfinder Panoramas land elevation collection, visualized in QGIS

\https://maps.gnosis.earth/ogcapi/collections/SRTM_ViewFinderPanorama/dggs/ISEA3H/zones?zone-level=10&bbox=30,40,50,50

Figure C.22 — GeoJSON compact zones response for querying ISEA3H DGGRS at level 10, using a (40°N, 30°E) to (40°N,50°E) bounding box, for a Viewfinder Panoramas land elevation collection, visualized in QGIS

\https://maps.gnosis.earth/ogcapi/collections/SRTM_ViewFinderPanorama/dggs/ISEA3H/zones?zone-level=16&parent-zone=E6-317-A

Figure C.23 — GeoJSON compact zones response for querying ISEA3H DGGRS at level 16, for parent zone E6-317-A, for a Viewfinder Panoramas land elevation collection, visualized in QGIS

C.6.2.  ISEA9R compact zone queries

Compacting ISEA9R zones can be achieved quite simply given that all sub-zones are fully congruent.

\https://maps.gnosis.earth/ogcapi/collections/SRTM_ViewFinderPanorama/dggs/ISEA9R/zones?zone-level=3

Figure C.24 — GeoJSON compact zones response for querying ISEA9R DGGRS at level 3 for a Viewfinder Panoramas land elevation collection visualized in QGIS

\https://maps.gnosis.earth/ogcapi/collections/gebco/dggs/ISEA9R/zones?bbox=30,40,50,60&zone-level=4

Figure C.25 — GeoJSON compact zones response for querying ISEA9R DGGRS at level 4 for a (40°N, 30°E) to (60°N,50°E) bounding box visualized in QGIS

\https://maps.gnosis.earth/ogcapi/collections/SRTM_ViewFinderPanorama/dggs/ISEA9R/zones?zone-level=4&parent-zone=B6-2

Figure C.26 — GeoJSON compact zones response for querying ISEA9R DGGRS at level 4 for parent zone B6-2, for a Viewfinder Panoramas, visualized in QGIS

\https://maps.gnosis.earth/ogcapi/collections/SRTM_ViewFinderPanorama/dggs/ISEA9R/zones?zone-level=8&parent-zone=E6-317

Figure C.27 — GeoJSON compact zones response for querying ISEA9R DGGRS at level 8 for parent zone E6-317, for a Viewfinder Panoramas, visualized in QGIS

C.6.3.  GNOSIS Global Grid compact zone queries

Compacting GNOSIS Global Grid zones is also simple to achieve since sub-zones are also fully congruent.

To illustrate how the width of the zones attempts to remain equal to the height, the following examples are visualized using the world Mercator projection. As with the previous examples for ISEA3H and ISEA9R, the zones of a given refinement level are filled with the same color. Note that the zones closer to the poles are wider in longitude than zones closer to the equator, and can be seen in a 2-to-1 configuration at jumps in the variable widths coalescence factor such as at the 45° parallel, but these zones still occupy a similar area within the error budget. However, in these illustrations, the polar zones appear much larger than zones of the same level closer to the equator because the Mercator projection enlarges features away from the equator.

\https://maps.gnosis.earth/ogcapi/collections/SRTM_ViewFinderPanorama/dggs/ISEA3H/zones?zone-level=5

Figure C.28 — GeoJSON compact zones response for querying GNOSIS Global Grid DGGRS at level 5 for a Viewfinder Panoramas land elevation collection visualized in QGIS

\https://maps.gnosis.earth/ogcapi/collections/gebco/dggs/GNOSISGlobalGrid/zones?bbox=30,40,50,60&zone-level=7

Figure C.29 — GeoJSON compact zones response for querying GNOSIS Global Grid DGGRS at level 7 for a (40°N, 30°E) to (60°N,50°E) bounding box visualized in QGIS

\https://maps.gnosis.earth/ogcapi/collections/SRTM_ViewFinderPanorama/dggs/GNOSISGlobalGrid/zones?zone-level=8&parent-zone=2-2-9

Figure C.30 — GeoJSON compact zones response for querying GNOSIS Global Grid DGGRS at level 8 for parent zone 2-2-9, for a Viewfinder Panoramas, visualized in QGIS

\https://maps.gnosis.earth/ogcapi/collections/SRTM_ViewFinderPanorama/dggs/GNOSISGlobalGrid/zones?zone-level=13&parent-zone=6-1F-98

Figure C.31 — GeoJSON compact zones response for querying GNOSIS Global Grid DGGRS at level 13 for parent zone 6-1F-98, for a Viewfinder Panoramas, visualized in QGIS

C.7.  Filtering zone queries using CQL2 expressions

The Zone Query capabilities is most useful for use cases where the retrieved zone list is the result of some operation, whether a processing workflow or the evaluation of a query expressed by the client. The CQL2 filter capability allows to express such queries using the OGC Common Query Language (CQL2). Note that the processing workflow could also itself include CQL2 expressions using input/output field modifiers.

The CQL2 requirement class in this standard specifically calls for the CQL2-Text encoding, which is an intuitive representation with many similarities to SQL. CQL2 defines minimum capabilities (Basic CQL2) as well as additional optional capabilities, such as arithmetic operations and spatial relation functions. The API implementation’s conformance resource (/conformance as defined in OGC API — Common — Part 1: Core “Landing Page” requirement class) would allow the client to know which capabilities are supported.

Basic CQL2 includes support for logical operators as well as to compare the value of queryables against literals using relational operators. The following examples will use the GEBCO collection from earlier ones to illustrate these capabilities. The previous simple zone queries using this collection were not particuarly interesting since it covers the entire globe, but the use of CQL2 will enable the use of its data values. First, the client would retrieve the queryables by following the [ogc-rel:queryables] link from the collection description:

https://maps.gnosis.earth/ogcapi/collections/gebco/queryables

The application/schema+json response would look like so:

{
   "$schema" : "https://json-schema.org/draft/2020-12/schema",
   "$id" : "https://maps.gnosis.earth/ogcapi/collections/gebco/queryables",
   "title" : "General Bathymetric Chart of the Oceans",
   "type" : "object",
   "properties" : {
      "Elevation" :
      {
         "type" : "number",
         "x-ogc-property-seq" : 1,
         "x-ogc-definition": "https://qudt.org/vocab/quantitykind/Altitude",
         "x-ogc-unit": "m"
      },
      "rec.geom" : {
         "x-ogc-role" : "primary-geometry",
         "format" : "geometry-point"
      }
   }
}

This informs the client that an Elevation queryable is available for use in CQL2 expressions. Although this collection is a gridded coverage, a rec.geom queryable is still included in the schema which represents the geometry of each individual grid cell. Since the value associated with these cells represent a point in this collection, the format indicates geometry-point. Later examples will make use of this rec.geom property.

The client could then submit the following zone query to return only zones where elevation is below sea level (Elevation < 0), at refinement level 6:

\https://maps.gnosis.earth/ogcapi/collections/gebco/dggs/isea3h/zones?filter=Elevation < 0&zone-level=6

The following image is a visualization of the list of zones returned.

Figure C.32 — GeoJSON compact zones response for querying ISEA3H DGGRS for GEBCO 2014 bathymetry with CQL2 expression Elevation < 0 visualized in QGIS

The client could request instead for deeper elevations e.g., Elevation < -4000:

\https://maps.gnosis.earth/ogcapi/collections/gebco/dggs/isea3h/zones?filter=Elevation < -4000&zone-level=6

Figure C.33 — GeoJSON compact zones response for querying ISEA3H DGGRS for GEBCO 2014 bathymetry with CQL2 expression Elevation < -4000 visualized in QGIS

or for high elevations e.g., Elevation > 3000:

\https://maps.gnosis.earth/ogcapi/collections/gebco/dggs/isea3h/zones?filter=Elevation > 3000&zone-level=6

Figure C.34 — GeoJSON compact zones response for querying ISEA3H DGGRS for GEBCO 2014 bathymetry with CQL2 expression Elevation > 3000 visualized in QGIS

or for either deep or high elevations e.g., Elevation < -4000 or Elevation > 3000:

\https://maps.gnosis.earth/ogcapi/collections/gebco/dggs/isea3h/zones?filter=Elevation < -4000 or Elevation > 3000&zone-level=6

Figure C.35 — GeoJSON compact zones response for querying ISEA3H DGGRS for GEBCO 2014 bathymetry with CQL2 expression Elevation < -4000 or Elevation > 3000 visualized in QGIS

This last visualization higlights the fact that the Andes and Antarctica mountains are actually very close to very deep sea.

If the implementation support spatial relation functions, a query could test intersection with a geometry, which can be expressed using a WKT literal in CQL2-Text. The following example returns zones intersecting the Bermuda Triangle, making use of the rec.geom queryable, which represents the geometry of the individual coverage grid cells, mentioned earlier, at refinement level 9.

https://maps.gnosis.earth/ogcapi/collections/gebco/dggs/isea3h/zones?zone-level=9=S_INTERSECTS(rec.geom,POLYGON-64.8%2032.3,-65.5%2018.3,-80.3%2025.2,-64.8%2032.3)&f=json[“https://maps.gnosis.earth/ogcapi/collections/gebco/dggs/isea3h/zones?zone-level=9&filter=S_INTERSECTS(rec.geom,POLYGON-64.8 32.3,-65.5 18.3,-80.3 25.2,-64.8 32.3)”]

Figure C.36 — GeoJSON compact zones response for querying ISEA3H DGGRS for GEBCO 2014 bathymetry with a CQL2 expression using S_INTERSECTS() for a WKT triangular polygon visualized in QGIS

This spatial filter could also be combined together with a relational operator as in the following query for Elevation < -5500 within the Bermuda Triangle:

https://maps.gnosis.earth/ogcapi/collections/gebco/dggs/isea3h/zones?zone-level=11=Elevation%20%20-5500%20and%20S_INTERSECTS(rec.geom,POLYGON-64.8%2032.3,-65.5%2018.3,-80.3%2025.2,-64.8%2032.3)&f=json[“https://maps.gnosis.earth/ogcapi/collections/gebco/dggs/isea3h/zones?zone-level=11&filter=Elevation < -5500 and S_INTERSECTS(rec.geom,POLYGON-64.8 32.3,-65.5 18.3,-80.3 25.2,-64.8 32.3)”]

Figure C.37 — GeoJSON compact zones response for querying ISEA3H DGGRS for GEBCO 2014 bathymetry with a CQL2 expression using both Elevation < -5500 as well as S_INTERSECTS() for a WKT polygon visualized in QGIS

To illustrate the use of CQL2 arithmetic operators, the following example will use a collection of daily climate CMIP5 data from the Copernicus Climate Data Store. The request will be for zones where the difference between two different fields of the coverage, the maximum (tasmax) and minimum (tasmin) daily near-surface air temperature, is greater than 10 degrees Kelvin. In addition, this request will use the datetime parameter to subset the temporal dimension for June 1, 2023.

\https://maps.gnosis.earth/ogcapi/collections/climate:cmip5:singlePressure/dggs/isea3h/zones?zone-level=7&filter=(tasmax-tasmin)>10&datetime=2023-06-01

Figure C.38 — GeoJSON compact zones response for querying ISEA3H DGGRS for CMIP5 daily surface temperature from Copernicus Climate Data Store comparing delta with CQL2 expression (tasmax - tasmin) > 10 visualized in QGIS

CQL2 expressions can also be used for queries using attributes of vector features. The following examples use a collection of building polygon features in Ottawa extracted from the OpenStreetMap dataset, filtering buildings using both a spatial subset and the name attribute of the features.

This first example illustrates querying for the National Arts Centre at ISEA3H level 30:

\https://maps.gnosis.earth/ogcapi/collections/osm:ottawa:buildings/dggs/ISEA3H/zones?subset=Lat(45.4198:45.4264),Lon(-75.704:-75.6935)&filter=name=’National Arts Centre’&zone-level=30

Figure C.39 — GeoJSON compact zones response for querying ISEA3H DGGRS for Ottawa buildings (© OpenStreetMap contributors) with CQL2 expression name='National Arts Centre' at level 30, visualized in QGIS

This second example illustrates querying for the East Block at ISEA9R level 15 (corresponding to ISEA3H level 30):

\https://maps.gnosis.earth/ogcapi/collections/osm:ottawa:buildings/dggs/ISEA9R/zones?subset=Lat(45.4198:45.4264),Lon(-75.704:-75.6935)&filter=name=’East Block’&zone-level=15

Figure C.40 — GeoJSON compact zones response for querying ISEA9R DGGRS for Ottawa buildings (© OpenStreetMap contributors) with CQL2 expression name='East Block' at level 15, visualized in QGIS

This third example illustrates querying for the Centre Block at GNOSIS Global Grid level 24 (corresponding approximately to same resolution):

\https://maps.gnosis.earth/ogcapi/collections/osm:ottawa:buildings/dggs/GNOSISGlobalGrid/zones?subset=Lat(45.4198:45.4264),Lon(-75.704:-75.6935)&filter=name=’Centre Block’&zone-level=24

Figure C.41 — GeoJSON compact zones response for querying GNOSIS Global Grid DGGRS for Ottawa buildings (© OpenStreetMap contributors) with CQL2 expression name='Centre Block' at level 24, visualized in QGIS

A future extension could also enable cross-collection queries, possibly using a joinCollections parameter which would make queryables from different collections available.

C.8.  Retrieving data for a DGGRS Zone

The following example retrieves elevation data for the GEBCO collection for ISEA3H zone A2-0-A at a relative depth of 8:

https://maps.gnosis.earth/ogcapi/collections/gebco/dggs/ISEA3H/zones/A2-0-A/data?zone-depth=8

Figure C.42 — Visualization of a DGGS JSON response for querying ISEA3H DGGRS for zone A2-0-A of GEBCO 2014 bathymetry at a relative depth of 8